home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 August / Macworld (1999-08).dmg / From Macworld Readers / FREE Scripts / FREE Scripts Vol 2 / FREE Scripts Volume 2 / FREE Scripts Volume 2 v1.1.sea / FREE Scripts Volume 2 v1.1 / • Third-party Software / FreePPP Control / ReadMe - FreePPP Ctrl < prev    next >
Text File  |  1997-08-17  |  11KB  |  188 lines
  1.  
  2. 
  3.  
  4. FreePPP Control 1.0b2 (16.Aug.1997)
  5. Scripting addition for FreePPP 2.6
  6.  by Sebastian Kloska
  7.  
  8.  
  9. About FreePPP Control...
  10.  
  11. FreePPP Control is a scripting addition which gives Applescript access to the main functions of the FreePPP 2.6 system extension.For more information about FreePPP please visit <http://www.rockstar.com/>.     
  12.  
  13. History
  14.  
  15. I’ve been using the scripting addition "MacPPP Control" by Mark Aldritt to automate my daily PPP access. It allows Applescript to open and close a specific PPP connection and set or ask for current state informations.  
  16.                 
  17. MacPPP Control always worked fine with MacPPP and FreePPP up to version 2.5v2 but the developers of FreePPP changed the API and the structure of the preferences file in a way that it won’t function with FreePPP 2.6. Having some spare time I started to work on my own replacement for the MacPPP scripting addition based on the public interface for FreePPP 2.6.
  18.  
  19. How to install FreePPP Control
  20.  
  21. Assuming that FreePPP 2.6 and Applescript are properly installed on your computer you just have to place the "FreePPP Control" Scripting Addition in your "Scripting Additions" Folder which should be located in your "System Extensions" Folder. You don’t have to restart. The new FreePPP Applescript commands are instantly available.     
  22.  
  23. What features does it add ?
  24.  
  25. FreePPP Control adds six new commands and one new class to your Applescript environment. If you’re starting your scripteditor and open the dictionary of FreePPP Control or simply drag the Scripting addition onto it you will get short informations about the newly added features.
  26.  
  27. New commands
  28.  
  29. • open FreePPP: Attempts to open a FreePPP connection
  30.  
  31.   Syntax: open FreePPP     
  32.  
  33. The command takes no arguments and returns no value. It simply tries to open the current PPP connection with the current settings. If there already is an active connection nothing happens.     
  34.  
  35. Note: "open FreePPP" initiates a new connection without waiting for success. If you want to be sure that you have an active connection you have to call "FreePPP is" or "FreePPP state".    
  36.  
  37. • close FreePPP: Attempts to close FreePPP connection
  38.  
  39.    Syntax: close FreePPP     
  40.  
  41. Tries to close the current connection. If there is none nothing happens. As with "open FreePPP" there is no return value. You have to use the "FreePPP is" command or the    "FreePPP state" verb to check for success.     
  42.  
  43. Caution: In contrast to the "MacPPP Control" scripting addition there is no way to force a hard close on the current connection. This behavior of FreePPP is strictly controlled by the current FreePPP settings. You can’t rely on "FreePPP Control" to actually close the telephone line for you. It simply closes the PPP stack to your ISP. 
  44.  
  45. • FreePPP is: check if FreePPP is connected or not connected
  46.  
  47.    Syntax: FreePPP is connected/not connected
  48.  
  49. There are two different ways to use the "FreePPP is"to check for a current connection. If you write "FreePPP is connected" the function returns true if your computer is currently connected otherwise false. A different approach is to ask if the computer is not connected by issuing the "FreePPP is not connected" command. The following statements within the if clause both are executed whenever FreePPP is currently on-line.     
  50.  
  51.   if FreePPP is connected then     
  52.   -- do something very usefull     
  53.   end if     
  54.  
  55.   if not FreePPP is not connected then     
  56.   -- do something even more usefull     
  57.   end if     
  58.                      
  59. • FreePPP set: set various parameters of FreePPP
  60.  
  61.    Syntax: FreePPP set     
  62.                  the current account/current location/current/modem     
  63.                  to string     
  64.                            
  65. The "FreePPP set" command enables Applescript to manipulatesome of the FreePPP settings like the account to use when dialing, the current modem and the present location. It takes two arguments. The first of them has to be introduced by the word "the" and determines the parameter you want to change. The second argument is preceded by "to" and specifies the new value.     
  66.  
  67. There is no return value. If the function failes the command returnes an error to Applescript and the script gets terminated. Valid arguments for new accounts, locations or modems have to be a part of the corresponding list (see "FreePPP get"). Names are case sensitive. The command also failes if there is a current connection. 
  68.  
  69. The following example first checks for FreePPP to be off-line and changes the name of the current modem to "MyBrandNew 56k Modem".     
  70.  
  71.    if FreePPP is not connected then     
  72.      FreePPP set the current modem to "MyBrandNew 56k Modem"     
  73.  end if     
  74.                  
  75. • FreePPP get: get various information from the FreePPP settings
  76.                      
  77.    Syntax: FreePPP get     
  78.                 the current account/current location/current modem     
  79.                 the list of accounts/list of locations/list of modems     
  80.  
  81. This command is used to query different settings of FreePPP. It takes one argument which is preceded by "the". There are two different classes of properties you can ask for. (1) If you request the name of the current account, location or modem a single string is returned which represents the name as it can be seen in the FreePPP Setup dialog. (2) If you ask for the list of accounts, locations or modems you'll get a list of strings representing valid names to choose from.  
  82.  
  83. The next example first determines the name of the current location and shows it in a dialog. Afterwards it'll show the list of valid account names one after the other .
  84.  
  85.   set the_account to FreePPP get the current account  
  86.   display dialog the_account  
  87.   --  
  88.   set the_list to FreePPP get the list of accounts  
  89.   repeat with a in the_list  
  90.     display dialog a 
  91.   end repeat
  92.                      
  93. • FreePPP state: get state of the current FreePPP connection
  94.  
  95.    Syntax: FreePPP state     
  96.  
  97. "FreePPP state" returns various information’s about the current PPP connection. The function takes no arguments and returns a record of class FreePPP-State.
  98.  
  99. New classes
  100.  
  101. • Class FreePPP-State: Information about the current PPP connection
  102.  
  103.   Properties: 
  104.    active    boolean          -- are we currently connected ?
  105.    duration  integer          -- Duration of the connection in seconds
  106.    bytes in  integer          -- Number of bytes in
  107.    bytes out integer          -- Number of bytes out
  108.    local IP  a list of small  -- IP address of your integer computer
  109.    remote IP a list of small  -- IP of the remote server integer 
  110.  
  111. This is the only new class defined by the "FreePPP Control" Scripting Addition. The record contains various information about an active PPP connection (if there is any) and it’s only purpose is to serve as a reply type for the "FreePPP state" command.     
  112.  
  113. The boolean value "active" reflects the on-line state of your computer. If it’s false there is  no connection. In this case the rest of the properties are not defined and can not be evaluated. Checking the "active" property gives the same result as calling "FreePPP is connected".     
  114.  
  115. The "duration" Property contains the number of seconds since the connection has been opened. "bytes in" and "bytes out" are counters holding the number of bytes written to and read from the PPP Server. The properties "local IP" and "remote IP" are lists of four integers which represent the IP of your computer and the server on the other side of the telephone.     
  116.  
  117. The following example gets the current FreePPP-State, determines if there currently is a connection and shows the local IP if FreePPP is active.     
  118.  
  119.   open FreePPP     
  120.   set a to FreePPP state    
  121.   --     
  122.   if active of a then     
  123.      set IP to ""     
  124.      --     
  125.      -- Transform the List into a string with dots     
  126.      --     
  127.      repeat with b in local IP of a     
  128.           set IP to (IP & b as text) & "."
  129.      end repeat     
  130.      --     
  131.      -- delete the trailing "."     
  132.      --     
  133.      set IP to items 1 thru ((number of items of IP)-1) of IP as text     
  134.      display dialog IP
  135.   end if
  136.  
  137. Error Messages
  138.  
  139. If something goes wrong the FreePPP Control Applescript addition returns an error message to the scripting system and terminates the script execution. There are (hopefully only) five types of error messages returned by the scripting addition.    
  140.  
  141. • "Neither MacTCP nor OpenTransport seems to be installed on  this System."
  142.  
  143. FreePPP Control wasn’t able to find any TCP/IP connection stack. Every command will terminate with this message if neither MacTCP nor OpenTransport is installed on your Computer.    
  144.                      
  145. • "FreePPP 2.6 or higher is not selected in the TCP/IP control pannel."
  146.  
  147. If OpenTransport is installed but FreePPP 2.6 is not selected as the current connection method some commands will terminate with this error message. "open FreePPP" and "close FreePPP" will fail whereas you’re still able to get and set current settings.     
  148.                      
  149. • "Either FreePPP 2.6 is not installed or it's not selected in the MacTCP control pannel."
  150.  
  151. If MacTCP provides the TCP/IP stack all commands require FreePPP to be the current connection method and will abort the script with this message.
  152.                  
  153. • "Command is illegal while FreePPP is connected"
  154.  
  155. You tried to set a new name for account, modem or location while the PPP connection was active. FreePPP Control is not able to change these parameters while on-line.
  156.                  
  157. • "Bad name for [account/location/modem]"
  158.  
  159. This message is triggered by an attempt to change the current modem, location or account name to something not listed in the FreePPP settings. Please keep in mind that these names are case sensitive. The best strategy to circumvent this message is to take a name out of the list obtained by the "FreePPP get" command.
  160.  
  161. FreePPP Control is a beta release
  162.  
  163. FreePPP Control 1.0b2 is a beta release.It is expected to be buggy.  I’ve been testing the program thoroughly but I don’t have the time to do this checking on various hardware platforms with different system configurations. Please keep me informed if there is any misbehavior of my program.
  164.  
  165. You can reach me via e-mail under <kloska@mpimg-berlin-dahlem.mpg.de>. Or visit my homepage <http://www.snafu.de/~sebastian.kloska/>    
  166.  
  167. FreePPP Control is Freeware
  168.  
  169. You may use FreePPP Control free of charge make as many copies as you like and distribute it on a non profit basis as long as it stays bundled with this unaltered documentation. For-profit companies that sell software programs must receive explicit written permission from the author before distributing the program.    
  170.  
  171. Version History
  172. • 1.0b1 (30.Juli.1997)
  173.   First public release of FreePPP Control
  174. • 1.0b2 (16.Aug.1997)
  175.   Replaced a wrong error message. Little improvement on the documentation.
  176.  
  177. Disclaimer
  178.  
  179. I make no warranty whatsoever, either implied or expressed, as to the correct functioning of this software. When using this software, the user assumes all responsibility for any damages caused, directly or indirectly, by its use.     
  180.  
  181.                 Sebastian Kloska; Katzlerstr 19;10829 Berlin;Germany
  182.                 mailto:kloska@mpimg-berlin-dahlem.mpg.de
  183.                 http://www.snafu.de/~sebastian.kloska/
  184.  
  185. FreePPP , the FreePPP Icon and FreePPP Setup are copyrights owned  by the FreePPP Group Inc. 
  186. Applescript is a registered trademarks  of Apple Computer, Inc.  
  187.  
  188.